Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

N3DShader

Inherits From:	Object

Declared In:	3Dkit/N3DShader.h

Class Description

N3DShader manages the application of shader functions to N3DShapes.  A shader function is written in the RenderMan Shading Language, compiled with the shading language compiler (see the shader(1) UNIX manual page), and contained in a shading language object file.  The RenderMan Shading Language is described in detail in The RenderMan Companion.  

Shader Functions and Shading Language Object Files

Each N3DShader instance manages a single shading language function.  A shader function is contained in a shading language object file.  The name of the shader function and shading language object file are the same (the file name has the extension .slo).  

When its shader function is set by the initWithShader: or setShader: methods, an N3DShader searches for the specified shader language object file in the current directory, and in the directory paths ~/Library/Shaders, /LocalLibrary/Shaders, and /NextLibrary/Shaders.  If the specified shader is found, the N3DShader's type, along with its arguments and their default values, is set.

The N3DShader class provides methods to determine these arguments for a particular shader function and to assign values for these arguments.  When rendering, the argument/value pairs are passed to the shader function.  You can reset any of an N3DShader's arguments to their default values using the resetShaderArg: method.

Shader Function Arguments

Each shader function can have an open-ended list of arguments.  The N3DShader class provides a number of methods for accessing these arguments and setting or retrieving their values.  

The method shaderArgCount returns the number of arguments for the function.  The method shaderArgNameAt: returns the name of each argument by zero-based index.  The method shaderArgType: returns the type of a named argument.  

The N3DShader class provides several methods to let you get and set the values for named arguments to a shader function.  These methods perform type conversion between the C-language, NEXTSTEP, and RenderMan types used in your application and the RenderMan Shading Language types used in the underlying shading function.  The shading language argument types are identified by members of an enumeration, SLO_TYPE, declared in the header file ri/slo.h.  The following table lists the correspondences between C-language types, shading language types, and methods:

C-language Type	SLO_TYPE	Methods

RtPoint	SLO_TYPE_POINT	getShaderArg:pointValue:
		setShaderArg:pointValue:
NXColor	SLO_TYPE_COLOR	getShaderArg:colorValue:
		setShaderArg:colorValue:
float	SLO_TYPE_SCALAR	getShaderArg:floatValue:
		setShaderArg:floatValue:
const char *	SLO_TYPE_STRING	getShaderArg:stringValue:
		setShaderArg:stringValue:

In general, you should use the shaderArgType: method to check an argument's type, then use the getShaderArg:...  and setShaderArg:...  method appropriate to the type of the argument.  While it's recommended that your application enforce these correspondences, the type conversion provided with each of the getShaderArg:...  and setShaderArg:...  methods is flexible enough to let you mix ostensibly incompatible data types.  The conversion schemes are somewhat complex but are documented with each of the getShaderArg:...  and setShaderArg:...  for the sake of completeness.  

N3DShader and N3DShape

RenderMan Shading Language functions are applied to specific surfaces in a scene.  In the 3D Graphics Kit, N3DShaders are applied by being associated with N3DShapes.  As the shapes in a shape hierarchy are rendered, the associated shader functions are called:  The shaders are thereby applied to that shape and its descendants.  Each N3DShape can apply six different shader types:  

surface
displacement
light
imager
volume
transformation

See the description of the render: method in N3DShape for an illustration of the order in which a shape's shader functions are invoked.  

N3DShader and the Interactive Renderer

While the PhotoRealistic RenderMan renderer can use any shader written with the RenderMan Shading Language, the Interactive RenderMan renderer uses only a limited set of shaders.  The surface type shaders that can be used by the interactive renderer are constant, matte, metal, plastic, and none.  The atmosphere shaders used by the interactive renderer are depthcue and fog.  Other than these, the interactive renderer ignores shading functions for performance reasons.

Instance Variables

NXColor color;

float transparency;

const char *shader;

SLO_TYPE shaderType;

int shaderArgCount;

SLOArgs *shaderArgs;

NXZone *zone;

color	Shader color

transparency	Shader transparency

shader	Name of the shader function

shaderType	Type of shader

shaderArgCount	Size of the array of shader arguments

shaderArgs	Array of shader arguments

zone	The zone in which the object's data resides

Method Types

Initializing and freeing 	- init
- initWithShader:
- free

Shader language object file	- setShader:
- shader

Shader color	- setColor:
- color
- setUseColor:
- doesUseColor

Shader transparency	- setTransparency:
- transparency

Shader function argument handling
- shaderArgCount
- shaderArgNameAt:
- shaderArgType:
- isShaderArg:
- setShaderArg:floatValue:
- setShaderArg:stringValue:
- setShaderArg:pointValue:
- setShaderArg:colorValue:
- getShaderArg:floatValue:
- getShaderArg:stringValue:
- getShaderArg:pointValue:
- getShaderArg:colorValue:
- resetShaderArg:

Shader type	- shaderType

Invoking the shader function	- set

Archiving	- read:
- write:

Instance Methods

color

- (NXColor)color

Returns the color of the shader.  

See also:  - setColor:, - setUseColor:, - doesUseColor

doesUseColor

- (BOOL)doesUseColor

Returns YES if the shader uses colors; NO if not.  

See also:  - color, - setColor:, - setUseColor:

free

- free

Frees the N3DShader and its data.  

getShaderArg:colorValue:

- getShaderArg:(const char *)colorName colorValue:(NXColor *)colorValue

Returns by reference the colorValue of the shader argument colorName.  This method should be used for shader function arguments of SLO_TYPE_COLOR.  Use the method shaderArgType: to check colorName's type before invoking this method.  See ªShader Function Argumentsº in the class description for a more complete discussion of how to get the type of an argument.  

If the argument colorName isn't a color type, this method converts the shading language type to an NXColor.  If the argument is a float, the argument's value is converted using the NXConvertGrayToColor() function.  If the argument is a string, the string value is converted to a float and then converted to a color with NXConvertGrayToColor().  If the argument is a point, its x-, y-, and z-coordinates are treated as r-, g-, and b-components and converted by the function NXConvertRGBToColor().  Returns self.  

See also:  - shaderArgType:

getShaderArg:floatValue:

- getShaderArg:(const char *)floatName floatValue:(float *)floatValue

Returns by reference the floatValue of the shader argument floatName.  This method should be used for shader function arguments of SLO_TYPE_SCALAR.  Use the method shaderArgType: to check floatName's type before invoking this method.  See ªShader Function Argumentsº in the class description for a more complete discussion of how to get the type of an argument.  

If the argument floatName isn't a float, this method converts the shading language type to a float.  If the argument is a color, the value is converted using the NXConvertColorToGray() function.  If the argument is a string, the string value is converted to a float.  If the argument is a point, its x-coordinate is returned.  Returns self.  

See also:  - shaderArgType:

getShaderArg:pointValue:

- getShaderArg:(const char *)pointName pointValue:(RtPoint *)pointValue

Returns by reference the pointValue of the shader argument pointName.  This method should be used for shader function arguments of SLO_TYPE_POINT.  Use the method shaderArgType: to check colorName's type before invoking this method.  See ªShader Function Argumentsº in the class description for a more complete discussion of how to get the type of an argument.  

If the argument pointName isn't a point type, this method converts the shading language type to an RtPoint.  If the argument is a color, the the r-, g-, and b-components of the color are assigned to the x-, y-, and z-cooordinates of pointValue.  If the argument is a float, all three components of pointValue return that value.  If the argument is a string, the string value is converted to and treated as a float.  Returns self.  

See also:  - shaderArgType:

getShaderArg:stringValue:

- getShaderArg:(const char *)stringName stringValue:(const char **)stringValue

Returns by reference the stringValue of the shader argument stringName.  This method should be used for shader function arguments of SLO_TYPE_STRING.  Use the method shaderArgType: to check stringName's type before invoking this method.  See ªShader Function Argumentsº in the class description for a more complete discussion of how to get the type of an argument.  

If the argument stringName isn't a string type, this method converts the shading language type to a string.  If the argument is a point, the string returned contains the x-, y-, and z-coordinates in order.  If the argument is a color, the string returned contains the r-, g-, and b-components in order.  If the argument is a float, the string returned contains the value.  Returns self.  

See also:  - shaderArgType:

init

- init

Initializes the receiver, a newly allocated instance of N3DShader.  The shader name is set to NULL.  The receiver's color is set to white and its transparency set to opaque (1.0).  

See also:  - initWithShader:

initWithShader:

- initWithShader:(const char *)aShader

Initializes the receiver, a newly allocated instance of N3DShader.  Invokes setShader: to set the receiver's shader to aShader.  

isShaderArg:

- (BOOL)isShaderArg:(const char *)argName

Returns YES if argName is the name of an argument for the shader owned by the N3DShader.

read:

- read:(NXTypedStream *)stream

Reads the receiver from the typed stream stream.  Returns self.  

See also:  - write:

resetShaderArg:

- resetShaderArg:(const char *)argName

Restores the default value for the shader argument argName.  

set

- set

Applies the receiver's shader function during rendering.  This method calls the appropriate RenderMan functionÐRiSurface(), RiAtmosphere(), and so onÐwith the N3DShader's shader name and arguments.  If the receiver is set to apply its color, this method calls RiColor() before calling the shader function.  

An N3DShape can have one each of six different N3DShader types.  This method is invoked by N3DShape's render: method on each of its N3DShader instances before the shape renders itself.  Returns self.  

See also:  - render: (N3DShape), - setColor:, - setUseColor:

setColor:

- setColor:(NXColor)aColor

Sets the color of the N3DShader to aColor.  Note that the effect produced by this method is distinct from that of setShaderArg:colorValue:, which is used to set an argument/value pair for a shader function.  Returns self.

See also:  - color, - setUseColor:, - doesUseColor

setShader:

- setShader:(const char *)aShader

Sets the receiver's shader function to aShader.  aShader must be the name of a shader language object file in the default shader search path.  Shader language object files are created by the shader compiler; each contains a single shader function.  

setShaderArg:colorValue:

- setShaderArg:(const char *)colorName colorValue:(NXColor)colorValue

Sets the value of the shader argument colorName.  This method should be used for shader function arguments of SLO_TYPE_COLOR.  Use the method shaderArgType: to check colorName's type before invoking this method.  See ªShader Function Argumentsº in the class description for a more complete discussion of how to get the type of an argument.  

If the argument colorName isn't a color, this method converts colorValue to the appropriate shading language type.  If the argument is a float, colorValue is converted using the NXConvertColorToGray() function.  If the argument is a string, colorValue's r-, g-, and b-components are placed in the string in order.  If the argument is a point, the r-, g-, and b-components of colorValue are set as the x-, y-, and z-components of the argument.  Returns self.  

See also:  - shaderArgType:

setShaderArg:floatValue:

- setShaderArg:(const char *)floatName floatValue:(float)floatValue

Sets the value of the shader argument floatName.  This method should be used for shader function arguments of SLO_TYPE_SCALAR.  Use the method shaderArgType: to check colorName's type before invoking this method.  See ªShader Function Argumentsº in the class description for a more complete discussion of how to get the type of an argument.  

If the argument floatName isn't a float, this method converts floatValue to the appropriate shading language type.  If the argument is a color, floatValue is converted using the NXConvertGrayToColor() function.  If the argument is a string, floatValue is converted to a string.  If the argument is a point, all three coordinates are set to floatValue.  Returns self.

See also:  - shaderArgType:

setShaderArg:pointValue:

- setShaderArg:(const char *)pointName pointValue:(RtPoint)pointValue

Sets the value of the shader argument pointName.  This method should be used for shader function arguments of SLO_TYPE_POINT.  Use the method shaderArgType: to check pointName's type before invoking this method.  See ªShader Function Argumentsº in the class description for a more complete discussion of how to get the type of an argument.  

If the argument pointName isn't a point, this method converts pointValue to the appropriate shading language type.  If the argument is a float, pointValue's x-coordinate is assigned to the variable.  If the argument is a string, the x-, y-, and z-coordinates of pointValue are placed in order in the string.  If the argument is a color, this method assigns the x-, y-, and z-coordinates of pointValue to the r-, g-, and b-components of the argument.  Returns self.  

See also:  - shaderArgType:

setShaderArg:stringValue:

- setShaderArg:(const char *)stringName stringValue:(const char *)stringValue

Sets the value of the shader argument stringName.  This method should be used for shader function arguments of SLO_TYPE_STRING.  Use the method shaderArgType: to check stringName's type before invoking this method.  See ªShader Function Argumentsº in the class description for a more complete discussion of how to get the type of an argument.  

If the argument stringName is a float, this method converts stringValue to a float. If the argument is a point or color, no conversion is made and the argument's value isn't changed.  Returns self.

See also:  - shaderArgType:

setTransparency:

- setTransparency:(float)alphaValue

Sets the transparency of the shader to alphaValue.  Returns self.  

setUseColor:

- setUseColor:(BOOL)flag

If flag is YES, sets the receiver to apply its color when rendering.  The color is set with the setColor: method, and is applied using the RiColor() RenderMan call.  Normally, this method is only invoked with flag YES for a surface type N3DShader.  Note that the effect produced by this method is distinct from that of setShaderArg:colorValue:, which is used to set an argument/value pair for a shader function.  

See also:  - set, - setColor:

shader

- (const char *)shader

Returns the name of the shader function associated with the N3DShader.  

shaderArgCount

- (int)shaderArgCount

Returns the number of arguments for the shader function associated with the N3DShader.  

shaderArgNameAt:

- (const char *)shaderArgNameAt:(int)argIndex

Returns the name of the argument at position argIndex in the list of shader function argument names.  To get all argument names, use this method to iterate through the list beginning with an argIndex of 0 and ending with an argIndex of

 [self shaderArgCount]-1 

shaderArgType:

- (SLO_TYPE)shaderArgType:(const char *)argName

Returns the type of the argument argName from the list of shader function argument names.  The value returned is an enumerated type, defined in the header file ri/slo.h.  If argName isn't found in the list, returns SLO_TYPE_UNKNOWN.  

shaderType

- (SLO_TYPE)shaderType

Returns the type of the shader function.  The value returned is an enumerated type, defined in the header file ri/slo.h.  If the receiving N3DShader doesn't have an associated shader function, this method returns SLO_TYPE_UNKNOWN.  

transparency

- (float)transparency

Returns the transparency (alpha) value set for the receiving N3DShader.  

write:

- write:(NXTypedStream *)stream

Writes the receiving N3DShader to the typed stream stream.  Returns self.  

See also:  - read: